.\" @(#)PAPI_flops    0.10 00/05/18 CHD; from S5
.TH PAPI_ipc 3 "September, 2004" "PAPI Programmer's Reference" "PAPI"

.SH NAME
PAPI_ipc \- PAPI High level: Simplified call to get instructions per cycle, real and processor time

.SH SYNOPSIS
.B C Interface
.nf
.B #include <papi.h>
.BI "int PAPI_ipc (float *" rtime ", float *" ptime ", long_long *" ins ", float *" ipc ");"
.fi
.B Fortran Interface
.nf
.B #include "fpapi.h"
.BI PAPIF_ipc(C_FLOAT\  real_time,\  C_FLOAT\  proc_time,\  C_LONG_LONG\  ins,\  C_FLOAT\  ipc,\  C_INT\  check )
.fi

.SH DESCRIPTION
.LP
The first call to
.B PAPI_ipc(\|)
will initialize the PAPI High Level interface, set up the counters
to monitor PAPI_TOT_INS and PAPI_TOT_CYC events and start the counters.
Subsequent calls will read the counters and return total real time,
total process time, total instructions since the start
of the measurement and the instructions per cycle rate since latest call to
.B PAPI_ipc(\|).
A call to
.B PAPI_stop_counters(\|) "
will stop the counters from running and then calls such as
.B PAPI_start_counters(\|) "
can safely be used.


.SH ARGUMENTS
.I *rtime 
-- total realtime since the first PAPI_ipc() call
.LP
.I *ptime 
-- total process time since the first PAPI_ipc() call
.LP
.I *ins  
-- total instructions since the first call
.LP
.I *ipc 
-- instructions per cycle achieved since the previous call

.SH RETURN VALUES
On success, this function returns
.B "PAPI_OK."
 On error, a non-zero error code is returned. 

.SH ERRORS
 In addition to the possible errors returned by the various PAPI
low level calls, the following errors could also be returned:
.TP
.B "PAPI_EINVAL"
The counters were already started by something other than:
.B PAPI_ipc(\|) 
.TP
.B "PAPI_ENOEVNT"
The total instructions or total cycles event does not exist.
.TP
.B "PAPI_ENOMEM"
Insufficient memory to complete the operation.
                                                                                
.BR  PAPI_ipc() " may be called by:"
.B  \t
.B  \tthe user application program
.fi
.LP
.nf
.B  \t
.BR  PAPI_ipc() " contains calls to:"
.B  \t
.B  \tPAPI_perror()
.B  \tPAPI_library_init()
.B  \tPAPI_get_hardware_info()
.B  \tPAPI_create_eventset()
.B  \tPAPI_add_event()
.B  \tPAPI_start()
.B  \tPAPI_get_real_usec()
.B  \tPAPI_accum()
.B  \tPAPI_shutdown()
.fi

.SH BUGS
This function has no known bugs.

.SH SEE ALSO
.BR "PAPI_stop_counters (3)", "PAPI_set_opt (3)", "PAPI_flips (3)",
.BR "PAPI_flops (3)"
